Skip to content

Write the three sites in the first person instead of naming a role - #230

Merged
iderex merged 1 commit into
mainfrom
voice/remove-a-role-word-from-tracked-files
Aug 31, 2026
Merged

Write the three sites in the first person instead of naming a role#230
iderex merged 1 commit into
mainfrom
voice/remove-a-role-word-from-tracked-files

Conversation

@iderex

@iderex iderex commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Closes #229.

What changed

Three tracked files carried a role word describing me from outside, at four
sites. All four are rewritten and none of them was replaced with a synonym.

docs/promotion.md said an experiment does not gain that role by being taken
somewhere. The sentence is about nobody taking on the duty of keeping the code
working, so it now says that instead of naming a post.

docs/quality-parity.md justified required_approving_review_count: 0 by a
property of the board's staffing. The reason is mine and is now written as
mine: I am the only reviewer here, and a count above zero would refuse every
merge.

internal/invariants/invariants.go named the tracker issue by that role twice

  • in the comment on DeclaredLicence and in the NotAsked message the licence
    leg prints. Both now name issue Decisions of mine this plan does not take #46, which is how every other reference to that
    issue in this tree is written and is a pointer a reader can follow instead of
    having to know who is meant.

The done-condition, run against the head of this branch

The issue's done-condition is that a case-insensitive grep for the word returns
only files whose vocabulary is somebody else's - a licence, a code of conduct
adopted verbatim, a platform syntax. Run at 7a24e99:

$ git grep -il <the word>
$ echo "exit=$?"
exit=1

It returns nothing at all, so there is no file of that last kind to name
here.
The issue asked me to list each such file with its reason; the list is
empty rather than omitted. LICENSE and DCO are the two files in this tree
whose text I did not write, and neither of them contains the word - which is
why the grep above is empty rather than showing two lines.

The means

Prose in the two documents and a comment plus a format string in Go, all of
them the means the files already use. Nothing is added: no language, no
runtime, no dependency, no new file. The change is four sentences, so the
means question here is only whether it belongs in the files that carry the
sentences, and it does.

Evidence, run on this branch before pushing

$ gofmt -l ./cmd ./internal
$ go build ./cmd/... ./internal/...
$ go test -count=1 ./cmd/... ./internal/...
ok  	github.com/Flowfin/lab/cmd/bom	23.217s
ok  	github.com/Flowfin/lab/cmd/contexts	1.231s
ok  	github.com/Flowfin/lab/cmd/lab	5.480s
ok  	github.com/Flowfin/lab/cmd/notices	23.897s
ok  	github.com/Flowfin/lab/cmd/pullrequest	1.194s
ok  	github.com/Flowfin/lab/internal/bom	1.578s
ok  	github.com/Flowfin/lab/internal/check	3.479s
ok  	github.com/Flowfin/lab/internal/contexts	1.434s
ok  	github.com/Flowfin/lab/internal/hardware	1.113s
ok  	github.com/Flowfin/lab/internal/invariants	2.728s
ok  	github.com/Flowfin/lab/internal/notices	1.478s
ok  	github.com/Flowfin/lab/internal/prose	2.111s
ok  	github.com/Flowfin/lab/internal/pullrequest	1.366s

$ go run ./cmd/lab check .
examined .
1 experiment directory walked, 1 record read
27 decision records read
the time this run read is 2026-08-31T07:53:24Z
0 refused

TestTheLicenceLegSaysWhetherItWasAsked asserts that the NotAsked message
still names #47, and it does: only the phrase carrying the role word moved,
and the issue reference the test reads is untouched. That test is inside the
internal/invariants line above and also runs in the invariants workflow.

What this does not do

It does not touch the four sentences' meaning anywhere except where naming the
role WAS the meaning, and in docs/promotion.md that is the one place a reader
should check me: I read "does not gain a role-holder" as "nobody takes on
keeping it working", and if that reading is wrong the sentence is now wrong in
a way the grep cannot see.

It adds no guard. Nothing in this tree refuses the word, so a fifth site
written tomorrow lands green. Making that refusable is not attempted here and
this pull request claims no protection against a recurrence.

This change has had no second reader. The evidence above stands in place of
one rather than alongside one, and every line of it is a command run at the head
being pushed.

)

Three tracked files described me from outside with a role word. I write in
the first person here, so the word is gone from all four of its sites and
each sentence now says the thing it was actually about.

docs/promotion.md said an experiment does not gain that role by being taken
somewhere. What the sentence means is that nobody takes on keeping it
working, and it now says so.

docs/quality-parity.md gave the reason for a required approving review count
of zero as a property of the board's staffing. The reason is mine: I am the
only reviewer here, and a count above zero would refuse every merge.

internal/invariants/invariants.go named the tracker issue by that role twice,
once in the comment on the declared licence and once in the message the
licence leg prints when it was not asked. Both now name issue #46, which is
how every other reference to it in this tree is written and is a pointer a
reader can follow.

The failure this prevents is text that reports on me in the third person
outliving the reason anybody wrote it that way, and a reference that can only
be resolved by knowing who is meant.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex iderex added the documentation Improvements or additions to documentation label Aug 31, 2026
@iderex iderex self-assigned this Aug 31, 2026
@iderex iderex added this to the 2. Repository scaffolding milestone Aug 31, 2026
@iderex
iderex merged commit 5500dc7 into main Aug 31, 2026
25 checks passed
@iderex
iderex deleted the voice/remove-a-role-word-from-tracked-files branch August 31, 2026 08:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove a role word from this project's tracked files

1 participant